###################
Documentation Guide
###################

.. note::

   In file paths in this document, a leading ``/`` denotes the Sphinx source root.

Structure
=========

The documentation for the Oklahoma NG911 GIS Toolkit for ArcGIS Pro is comprised of a few main sections (source files/directories in parentheses):

- User Manual (``/user-manual``)
- ``ng911ok`` API Documentation (``/apidoc``)
- Developer Guide (``/developers``)
- Toolkit Glossary (``/glossary.rst``)
- Validation Issue Glossary (``validation-issues.rst``)

The documentation is written in reStructuredText_ and built with Sphinx_. It uses the `PyData Sphinx Theme`_ and that theme's corresponding version of `Sphinx Design`_. It uses a number of Sphinx extensions, including built-in extensions, custom extensions, and |sphinxcontrib.programoutput|_.

Automatically-Generated Documentation
-------------------------------------

The ``ng911ok`` API Documentation is generated from docstrings using the ``apidoc`` Sphinx extension (``sphinx.ext.apidoc``). The resulting output is written to ``/apidoc``.

Supporting Files
----------------

Images used in the documentation are stored in ``/images``. Screenshots used in the User Manual section are stored in ``/images/UserManual``.

Custom Sphinx Functionality
===========================

Custom Extensions
-----------------

A number of custom Sphinx extensions have been written for this documentation. The added functionality is discussed below. The Python source files are stored in ``/_ext``, and other supporting files, such as stylesheets, are stored in ``/_static``.

Custom Sphinx Roles
-------------------

.. note::

   As used by Sphinx, the term "role" denotes specially-interpreted text that may be rendered differently than the text around it. This is unrelated to the ``role`` attribute of the :class:`~ng911ok.lib.config_dataclasses.NG911Field` and :class:`~ng911ok.lib.config_dataclasses.NG911FeatureClass` classes.

   In this section, the terms "Sphinx role" and "``role`` attribute" will be used to distinguish between the two.

The following custom Sphinx roles are defined:

.. list-table::
   :header-rows: 1

   * - Sphinx Role
     - Rendered
     - Corresponds To
     - Example
   * - ``ng911field``
     - :ng911field:`%Field`
     - :class:`NG911Field.role <ng911ok.lib.config_dataclasses.NG911Field.role>`
     - ``:ng911field:`field_role_attribute```
   * - ``ng911fc``
     - :ng911fc:`%Feature Class`
     - :class:`NG911FeatureClass.role <ng911ok.lib.config_dataclasses.NG911FeatureClass.role>`
     - ``:ng911fc:`feature_class_role_attribute```
   * - ``ng911domain``
     - :ng911domain:`%Domain`
     - :class:`NG911Domain.name <ng911ok.lib.config_dataclasses.NG911Domain.name>`
     - ``:ng911domain:`domain_name```
   * - ``ng911ds``
     - :ng911ds:`%Feature Dataset`
     - ``required`` or ``optional``
     - ``:ng911ds:`required```
   * - ``ng911tool``
     - :ng911tool:`Validate Geodatabase`
     - ``label`` attribute of tool classes in :mod:`ng911ok.tools`
     - ``:ng911tool:`Tool Name```
   * - ``bdg-contrast``, ``bdg-link-contrast``, ``bdg-ref-contrast``
     - :bdg-contrast:`Text`
     - The provided interpreted text
     - ``:bdg-contrast:`Text```
   * - ``bdg-contrast-line``, ``bdg-link-contrast-line``, ``bdg-ref-contrast-line``
     - :bdg-contrast-line:`Text`
     - The provided interpreted text
     - ``:bdg-contrast-line:`Text```

The ``:bdg-contrast:``, ``:bdg-contrast-line``, and similar Sphinx roles are derived from Sphinx Design's ``bdg-`` Sphinx roles. Specifically, they are similar to ``:bdg-light:``, ``:bdg-light-line`` (and similar) when the dark theme is active, and they are similar to ``:bdg-dark:`` and ``:bdg-dark-line:`` (and similar) when the light theme is active.

For ``:ng911field:``, ``:ng911fc:``, ``:ng911domain:``, and ``:ng911ds:``, if the text starts with a percent sign (``%``), that character itself will be removed, but whatever text that follows it will be preserved; this functionality is intended to be used only for demonstration purposes (e.g., to produce the contents of the "Rendered" column in the table above).

In the case of fields and feature classes, the provided ``role`` attribute will be replaced with the ``name`` attribute. This ensures that the correct field or feature class name will always be reflected when using these custom Sphinx roles, even if the ``name`` attributes change in a future version of the Standards.

For fields, the interpreted text can include, after the role, a comparison operator (``=``, ``<``, ``>``, ``<=``, ``>=``, ``!=``) followed by arbitrary text. If the arbitary text starts with ``$`` and is followed by an attribute of :class:`~ng911ok.lib.config_dataclasses.NG911Field`, the value of that attribute will be inserted. For example, ``:ng911field:`addnumber>=0``` will produce :ng911field:`addnumber>=0`, and ``:ng911field:`city=$fill_value``` will produce :ng911field:`city=$fill_value`.

In the case of tools, the rendered output will link to the corresponding tool class in :mod:`ng911ok.tools`, but the text itself will not be changed.

These custom Sphinx roles are implemented in the modules in ``/_ext`` and the stylesheets are located in ``/_static`` (where ``/`` denotes the Sphinx source root).

Toolkit Documentation
=====================

The Toolkit documentation is written in Markdown.

Using `Visual Studio Code`_ with the `Markdown All in One`_ extension, the documentation can be exported as HTML every time the Markdown files are saved.

.. _reStructuredText:
   https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

.. _Sphinx:
   https://www.sphinx-doc.org/en/master/

.. _PyData Sphinx Theme:
   https://pydata-sphinx-theme.readthedocs.io/en/stable/

.. _Sphinx Design:
   https://sphinx-design.readthedocs.io/en/pydata-theme/

.. _Visual Studio Code:
   https://code.visualstudio.com/

.. _Markdown All in One:
   https://marketplace.visualstudio.com/items/?itemName=yzhang.markdown-all-in-one

.. |sphinxcontrib.programoutput| replace:: ``sphinxcontrib.programoutput``

.. _sphinxcontrib.programoutput:
   https://sphinxcontrib-programoutput.readthedocs.io/en/stable/